<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Auto-refresh overview</title>
  <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<body text="#000000" bgcolor="#FFFFFF">
 
<h1>Auto-refresh overview</h1>
<font size="-1">Last modified: February 20, 2004</font> 
<p>
In Eclipse 3.0 an auto-refresh facility was added to the 
org.eclipse.core.resources plugin.  This feature, when enabled, searches
the file system for changes that have been made externally, and then
automatically refreshes the workspace when new changes are discovered. This
document briefly describes the architecture of auto-refresh.
</p>
<p>
Plug-ins provide change notification to the workspace by hooking into the
new <tt>refreshProviders</tt> extension point.  Extensions to this extension
point implement subclasses of the following abstract class:
<pre>
public abstract class RefreshProvider {
	public abstract IRefreshMonitor installMonitor(IResource resource, IRefreshResult result);
}
</pre>
</p>
<p>
When a new project or linked resource is added to the workspace, each installed
refresh provider is asked to install a refresh monitor on that location. If for any 
reason a refresh provider is not able to monitor a given location, it can opt not to 
return a monitor.  If no installed refresh providers are willing to monitor the location
(or if no refresh providers are installed), a default refresh provider is implemented
by the platform. This default refresh provider uses a naive Java-based polling
loop that manually checks for changes in the location at a specified interval
(by default, 30 seconds).
</p>
<p>
Once installed, a monitor is responsible for notifying the workspace when external 
changes are made to that file system location by invoking methods on the provided 
callback interface (<tt>IRefreshResult</tt>).  The results are collected by the
workspace, and the workspace will synchronize the changed resources in
a periodic background job. Note that this hand-off is entirely asynchronous.
The monitor is responsible for identifying out of sync resources, and in a separate
thread the workspace will process those changes and reconcile them with
the workspace tree.
</p>
<p>
The Eclipse SDK includes refresh provider implementations for both Win32 and Linux
platforms.  On all other platforms, the default Java-based polling refresh provider
is used, unless another plug-in is installed that provides a more efficient
platform-specific implementation. On Windows, the refresh provider uses win32
API calls to install a native file system monitor (FindFirstChangeNotificationW
in windows.h).  File system monitors in win32 are <b>deep</b>, i.e., they report
changes on an entire file sub-tree.
</p>
<p>
On Linux, the refresh provider use a standard Unix utility
called FAM (File Alteration Monitor), that is installed by default on most Linux
distributions. FAM runs a daemon that uses a native polling loop to detect changes in
the file system. Clients can install a monitor on individual directories, and they are
provided with a change event queue that they can process at will (either with a blocking
dequeue operation or by peaking at the queue in their own polling loop).  FAM
monitors are <b>shallow</b>, i.e., you need to install separate monitors on
each folder of a sub-tree.
</p>






</body>
</html>